_p_o_r_t expects the AAAALLLLppppoooorrrrtttt structure for the audio port to which
you want to write samples. This structure is the returned
value of the AAAALLLLooooppppeeeennnnppppoooorrrrtttt((((3333ddddmmmm)))) call.
_s_a_m_p_l_e_s expects a pointer to a buffer from which you want to
transfer the sound samples into the audio port.
_s_a_m_p_l_e_c_o_u_n_t expects the number of samples that you want to write to the
port.
DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss is obsolete and is provided for backward compatibility. The
preferred function is aaaallllWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss((((3333ddddmmmm)))), which uses units of sample
frames.
AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) writes samples to the audio port buffer. If there is
not sufficient buffer space in the audio port, AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) will
block until enough space becomes available for the transfer to complete.
Normally, AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) will return before the sound has finished
playing.
To delay until the sound has finished playing, keep calling
AAAALLLLggggeeeettttffffiiiilllllllleeeedddd((((3333ddddmmmm)))) and ssssggggiiiinnnnaaaapppp((((2222)))) until AAAALLLLggggeeeettttffffiiiilllllllleeeedddd((((3333ddddmmmm)))) returns 0, or set
the fillpoint to the queuesize minus one and call sssseeeelllleeeecccctttt((((2222)))) or ppppoooollllllll((((2222)))).
By calling AAAALLLLggggeeeettttffffiiiillllllllaaaabbbblllleeee((((3333ddddmmmm)))) you can determine how many samples will fit
into the internal buffer without blocking.
The _s_a_m_p_l_e_s buffer is interpreted differently depending on the current
configuration of the port. In particular, the _w_i_d_t_h setting specified by
AAAALLLLsssseeeettttwwwwiiiiddddtttthhhh((((3333ddddmmmm)))) determines which of the bits in the buffer make up the
sound samples. Samples of width AAAALLLL____SSSSAAAAMMMMPPPPLLLLEEEE____8888 ((((cccchhhhaaaarrrr)))) and AAAALLLL____SSSSAAAAMMMMPPPPLLLLEEEE____11116666
((((sssshhhhoooorrrrtttt)))) are treated as normal signed numbers which contain the most
significant 8 or 16 bits of the audio amplitude measurement,
respectively. Samples of width AAAALLLL____SSSSAAAAMMMMPPPPLLLLEEEE____22224444 ((((lllloooonnnngggg)))) are treated as signed
24 bit numbers packed into the low 24 bits sign extended to fill a long.
They may be treated as longs in the range -8388608 to 8388607. Only the
least significant 24 bits of the long are used by the audio hardware.
In the case that the port is configured to use floating point or double
precision floating point samples (see AAAALLLLsssseeeettttssssaaaammmmppppffffmmmmtttt((((3333ddddmmmm))))), the _w_i_d_t_h
setting is ignored, and the samples are treated as floating point or
When you send samples to a stereo audio port, AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) sends the
odd numbered samples to the right channel and sends the even numbered
samples to the left channel. This notion of odd and even includes all the
samples that have ever been sent to this port, so channel swapping
confusion can be avoided by always sending an even number of samples to a
stereo audio port (i.e. _s_a_m_p_l_e_c_o_u_n_t is an integer multiple of the frame
size, in this case 2).
In the case of a 4-channel port, you should write only an integer number
of frames of data (viz., samplecount should be a multiple of 4) to a
port. If a non-integer number of frames is written to a port,
AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) will not transfer the samples and will return an error.
Though 4-channel audio ports can be opened successfully for all IRIS
workstations with high-quality audio, not all hardware can support 4
line-level electrical connections (e.g. Indigo). In the case that the
hardware is unable to support these connections, AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) will
mix the two pairs of samples to a stereo signal.
Consider the following situation: 4 samples (L1, R1, L2, R2) are written
to a 4-channel port on a machine without the 4-channel capability. In
this case, the 4 samples will be summed to 2 samples in the following
manner: (L1, R1, L2, R2) becomes (L1+L2, R1+R2). These sums are then
limited to avoid overflow and sent to the audio hardware as a stereo
pair. Thus, no information is lost when using a 4-channel port on a
machine without the 4-channel capability.
In the case that the hardware is capable of 4 line-level output signals
AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) will send the samples (L1, R1, L2, R2) to the output
connections in the following manner: sample pair (L1, R1) will be sent to
the regular line-level output; and sample pair (L2, R2) will be sent to
the headphone output (which is electrically configured to line-level by
AAAALLLLsssseeeettttppppaaaarrrraaaammmmssss((((3333ddddmmmm)))) using the AL_CHANNEL_MODE/AL_4CHANNEL parameter/value
pair).
You can determine whether a system has the 4-channel capability with
AAAALLLLggggeeeettttmmmmiiiinnnnmmmmaaaaxxxx((((3333ddddmmmm)))). Once you have determined that a system does possess
this capability, you can configure the system for 4-channels with
AAAALLLLsssseeeettttppppaaaarrrraaaammmmssss((((3333ddddmmmm)))). Note that hardware with the 4-channel capability must
be configured to have the proper 4-channel line-level connections. By
default, all hardware will behave as a stereo device.
If you want to change the sample format, the maximum value for floating
point/double precision data, or sample size settings, you can call
AAAALLLLsssseeeettttssssaaaammmmppppffffmmmmtttt((((3333ddddmmmm)))), AAAALLLLsssseeeettttffffllllooooaaaattttmmmmaaaaxxxx((((3333ddddmmmm)))), and AAAALLLLsssseeeettttwwwwiiiiddddtttthhhh((((3333ddddmmmm)))) followed by a
call to AAAALLLLsssseeeettttccccoooonnnnffffiiiigggg((((3333ddddmmmm)))).
AAAALLLLwwwwrrrriiiitttteeeessssaaaammmmppppssss((((3333ddddmmmm)))) can fail for the following reason:
AAAALLLL____BBBBAAAADDDD____TTTTRRRRAAAANNNNSSSSFFFFEEEERRRR____SSSSIIIIZZZZEEEE _s_a_m_p_l_e_c_o_u_n_t is not a multiple of the frame size
set by AAAALLLLsssseeeettttcccchhhhaaaannnnnnnneeeellllssss((((3333ddddmmmm)))). This error pertains to
